BizTalk 2009 : Using XML Namespaces (part 1) - Understanding Property Promotions

XML namespaces generally take the following form:

http://companyname.com/Project/Subsystem/

Defining custom namespaces is crucial for the following reasons:

• They provide unique names for elements and attributes.

• They prevent naming conflicts with other schemas.

• You can use them for code generation. The namespace will be used to generate the type that represents the schema within the assembly once it is compiled.

• The schema's namespace#root combination must be unique unless you are creating a probing pipeline.^[] However, schemas with the same namespace#root combination can be placed in the GAC without being deployed and used by some other components.

When creating a BizTalk schema, the following namespaces are automatically included by default:

xmlns:b="http://schemas.microsoft.com/BizTalk/2003"
xmlns:xs="http://www.w3.org/2001/XMLSchema"

These namespaces are included to allow the schema to reference common elements that are required by the BizTalk runtime.

1. Understanding Property Promotions

When new BizTalk developers are asked to "promote a property," they all perform the same task: they open up the schema editor, right-click the element, and choose Quick Promotion. Most have no idea about what is actually happening under the covers or how this element will move into the message's context. Property promotion and the message context are keys to the Message Bus architecture within BizTalk and need to be properly understood.

1.1. Promoted Properties

Promoted properties are advantageous, because they allow the Messaging Engine to route messages looking only into the message context. If the property that you need to route on does not exist within one of the default property schemas, you will need to create a custom property schema that is used within your project.

Promoted properties are the most common way to enable content-based routing, because promoted properties are available to pipelines, adapters, the Message Bus, and orchestrations. To promote a property within BizTalk Server, you have two options—quick promotion and manual promotion.

1.1.1. Quick Promotion

Quick promotion is the simplest way to promote an element's value into the message context. To quick promote, all you do is right-click the element's node and choose Quick Promotion. The BizTalk schema editor will create a new property schema and add an XML reference to the new property schema. By default the new schema is called PropertySchema.xml, although this can be changed by editing the properties of the schema file. Each property you promote using a quick promotion will create a corresponding element in the new property schema with the same name and type as in the source schema. When the pipeline associated with the port parses the inbound message, it will move the value from the message's data payload into the message context and assign the namespace of that property to the name defined in the property schema for that element.

1.1.2. Manual Promotion

Manually promoting a property using a custom property schema involves creating a new property schema and creating elements that will hold the promoted values. Once all the elements are created, the property schema is associated to the main content schema by choosing the Show Promotions function in the schema editor. Every element that is defined in the promotions section of the schema will be promoted automatically when the pipeline processes the message. Manual promotions are also useful when you want to store values in the system property namespaces.

1.2. Promoting vs. Writing

Promoted properties defined in a property schema can have one of two base types: MessageDataPropertyBase or MessageContextPropertyBase. If a property is inherited from MessageDataPropertyBase, then the value of the property comes from the payload of the message. Properties defined in property schemas are derived of this type. Properties derived from MessageContextPropertyBase do not have values from the message payload, but they will generally contain data that relates to the transport of the message and can have configuration information necessary for the subscription to be evaluated. Properties with MessageContextPropertyBase as their base type are often promoted by adapters and pipelines and generally include values necessary for the adapter to process the message.

When defining property schemas and coding custom pipeline components and adapters, it is crucial to understand the difference between the two base types and how the BizTalk Messaging Engine treats them. Should the property inherit from MessageDataPropertyBase, the orchestration design engine (ODX) examines the property and checks to see whether the namespace and property name match a promoted property. If no promoted property exists in the schema and no matching property is found, the ODX design surface does not allow you to see the property. Inheriting a property from MessageContextPropertyBase allows you to see the property regardless of its namespace.

As mentioned previously, the API for writing vs. promoting is essentially the same, but there are two separate methods. On the IBaseMessageContext object of every message in BizTalk, there is a Write() method and a Promote() method. Both of these methods take the property name, the namespace, and the value. For the property to be available for routing, when promoting a property, the namespace and property name must be the same as those defined in a referenced property schema. This process is different if you want to dynamically write a distinguished field. Distinguished fields are special context properties that can be directly accessed from the expression editor through IntelliSense within an orchestration. If you need to write a distinguished field, you must use the distinguished field namespace of http://schemas.microsoft.com/BizTalk/2003/btsDistinguishedFields. The name of the property must be a valid XPath expression to the element being written to the context. The following code sample illustrates how to dynamically promote and write properties to the message context from code:

//BizTalk system properties namespace
Private Const BTSSystemPropertiesNamespace As String = _
"http://schemas.microsoft.com/BizTalk/2003/system-properties"

Private Const BTSDistinguishedFieldsPropertiesNamespace As String = " _
http://schemas.microsoft.com/BizTalk/2003/btsDistinguishedFields"

//Promote the MessageType property
messageType = "http://" + "schemas.abc.com/BizTalk/" + "#" + "Request"
message.Context.Promote("MessageType", BTSSystemPropertiesNamespace, messageType);

//Write a transient value to the message context
message.Context.Write("MyVariable", "SomeNameSpace", SomeData);

//Write a distinguished property
message.Context.Write("OdxProperty", BTSDistinguishedFieldsPropertiesNamespace,
myVar);

					  

1.3. Considerations When Promoting Properties

Blindly promoting properties is not only inefficient, but it can also be costly in terms of both performance and scalability. The following is a short list of items to be considered before promoting a property into the message context:

• Property size: To increase routing performance, promoted properties are limited to 255 characters. There is no limit to the size of properties that are simply written to the context. However, writing large properties to the message context will still decrease performance, because the Messaging Engine still needs to process and manage the context regardless of how big it is.

• Performance: All promoted fields are explicitly inserted into a database table in order to make them available to the subscription resolution stored procedure. If you promoted more properties than actually necessary "just in case," you would waste the cycles of inserting those fields and evaluating them against subscriptions. Also note that large message properties cannot be "streamed" and must be entirely loaded into memory by the runtime. This will become an issue if you write large values for message properties into the message context.

• Overwriting of promoted properties: If you have promoted a property to the message context and you issue a context write operation, the property is no longer promoted.

• Dealing with Nulls: Null properties are not persisted to the context. If you set a property's value to Null, it will no longer exist, and you cannot see a context property in the MMC with a value of Null.

1.4. Distinguished Fields

There are two types of property promotion: distinguished fields and property fields. The latter type uses property schemas. In the BizTalk schema editor, you manage both of these types of property promotion by using the Promote Properties dialog box, which you access either by using the Promote Properties property of the Schema node or by right-clicking a node in the tree and selecting the Promote menu item. Distinguished fields are useful only when they are accessed within orchestration. Promoted properties can be accessed either in orchestrations or from custom code, routing, and pipelines.

Distinguished fields, on the other hand, cannot be used for routing and are used only by the orchestration engine. When dealing with large messages, this can save significant server processing, because the engine would need to use XPath expressions to search through the document to find the piece of data that it needs each time the expression is evaluated. This way, the data is loaded once when the document is parsed by the runtime engine. Distinguished fields are used within orchestrations to move required elements into the context and read the context property only within the orchestration without having to load the entire document into memory. Distinguished fields also offer nice IntelliSense capabilities within the orchestration expression editor and message assignment shapes.

Depending on the type of access that is needed, you can choose to create either promoted properties or distinguished fields depending on how the property will be used.